Nous allons décrire le projet et ses enjeux de façon plus approfondie. 
Le but premier était de réaliser un outil de génération de documentation à partir de fichier sources SIDL. Pour parser les fichiers sources, il existait déja la fonction python \textit{gendoc}. Elle était appelée par l'option \textit{gendoc} de la commande \textit{atmake}. Cette fonction était vide au commencement du projet et l'une des phase était de la remplir. Nous ne nous attarderons pas sur cet aspect du développement mais plus sur la partie qui se centrait sur l'aspect IHM, et donc sur la partie utilisant le framework Flex. En effet, un des enjeux de ce projet était de créer un outil nommé Jam qui soit assez poussé d'un point de vue IHM.


\subsection{Analyse de l'existant}

Afin de réaliser un logiciel de documentation efficace, il fallait d'abord s'informer sur les produits analogues existants sur le marché, les plus célèbres sont Javadoc et Doxygen. Il faut savoir que Doxygen est bien plus proche de Jam car il ne se contente pas de générer la documentation pour le langage Java. Il prend aussi en compte les langages C, C++, PHP, et bien d'autres. Nous allons donc détailler en premier ses caractéristiques.

\subsubsection{Doxygen}

Tout d'abord, il faut savoir que Doxygen est sous licence GPL\footnote{General Public License}. Ce logiciel existe depuis 1997 et permet de documenter une dizaine de langages de programmation. Voici d'ailleurs la liste exhaustive de tous ces langages : C, C++, Java, Objectif-C, Python, IDL, Fortran, VHDL, PHP, C$\sharp$, et quelques extensions du D.
Bien entendu, seuls les langages C et C++ seront traités ici car ils concernent directement le projet Jam.

\paragraph{}Il faut regarder sous quels formats sortent les documentations. Il y en a principalment deux : le HTML et le \LaTeX. Evidemment, la majorité ce qu'écrit le rédacteur se retrouve dans les parties de la documentation.

\paragraph{}Doxygen utilise tout un langage balisé rappelant légèrement \LaTeX. Il ne permet évidemment pas de réaliser une mise en forme aussi détaillée, mais se présente plus comme une sur-couche au \LaTeX. Il permet pour chaque élément documentable de définir, par exemple, l'auteur, la version de l'élément, la date à laquelle il a été créé. Lors de l'utilisation de Doxygen, il est aisément perceptible que ce logiciel a été éprouvé par le temps. Il est en effet extrèmement simple à comprendre.

\paragraph{}L'aspect qui suit montre les principales commandes de Doxygen afin de mieux comprendre comment fonctionne un générateur de documentation.
Voyons d'ailleurs les plus importantes d'entre elles :\newline

\begin{itemize}
 \item Les balises $\backslash$file, $\backslash$class, $\backslash$fun, $\backslash$struct : Ces balises permettent de définir la documentation sur l'élément étudié. On remarque vite à quel point l'outil est avancé. Par exemple, si l'on détermine la documentation d'un fichier, il est inutile de donner la moindre information pour qu'automatiquement les fonctions y étant incorporées soient détectées. Il est évident qu'elles n'apparaissent pas dans le document PDF si elles ne sont pas documentées, mais elles sont visibles sur la page HTML.\\

 \item Les balises $\backslash$brief, $\backslash$date, $\backslash$version, $\backslash$author : Ces balises permettent de donner des informations sur l'élément déja choisi. Par exemple, si une balise $\backslash$brief est placée après une balise $\backslash$file, alors le brief concernera le fichier en question. La balise $\backslash$brief permet de définir un résumé de l'élément documenté. La balise $\backslash$version permet de donner la version. Il en va de même pour les balises $\backslash$date et $\backslash$author.\newline

 \item Les balises $\backslash$mainpage, $\backslash$page, $\backslash$subpage, $\backslash$section : Ces balises permettent de définir des pages de documentation n'étant pas directement liées à un élément du code. En effet, ces pages pourraient s'apparenter à de la vulgarisation permettant d'expliquer le code dans sa globalité. Pour bien contruire ces pages, il faut les relier les unes aux autres. En effet, on peut créer un lien vers une autre page en utilisant la balise $\backslash$subpage. Au niveau de la documentation HTML, l'onglet \textit{Related Pages} permet de voir la liste de toutes les pages non atteignables. Au niveau du document PDF généré par le fichier \LaTeX, il est assez regrettable que les liens ne soient pas opérationels. Bien qu'ils soient clickables, ils renvoient tous à la première page du document.\\

 \item Les balises $\backslash$ref et $\backslash$anchor : ces balises sont quand à elles extrèmement intéressantes. En effet, elles permettent de réaliser des liens hypertextes vers différentes parties de la documentation. Si l'on utilise une balise $\backslash$ref directement, on peut rejoindre n'importe quel autre objet de documentation déja défini, tel qu'une page, une section, ou même un fichier de code. Mais pour plus de précisions, on peut poser des ancres avec la balise $\backslash$anchor. De cette façon il est possible de cibler plus précisement certaines parties de la documentation, ou tout simplement de créer des raccourcis dans la même page. Ce mécanisme ne fonctionne pas seulement pour la documentation HTML, mais également pour le document \LaTeX généré.\newline
\end{itemize}

\paragraph{}Naturellement, il reste beaucoup d'autres balises, mais la sélection présentée ci-dessus permet d'observer et de comprendre les principaux mécanismes de Doxygen. Bien que ce fut laborieux, ce rappel était nécessaire afin de mieux comprendre les éditeurs de documentations.
Sur l'ergonomie du balisage, quelques remarques peuvent donc être faite :\newline
\begin{itemize}
 \item Afin de définir la documentation d'un élément, il est nécessaire de préciser tout d'abord quel est l'élément ou le fichier à décrire. L'emplacement où se trouvent ces balises n'influent en rien.\newline
 \item Il est très intéressant de pouvoir observer le code source de certains fichiers, mais il est dommage que ce ne soit que des \textit{.h}\newline
 \item Les fichiers ne disposant d'aucune documentation sont totalement invisibles. C'est dommage car Doxygen Trouve pourtant leurs fonctions et les référence, même si aucune n'est documentée.\newline
 \item Le fait que des fichiers \LaTeX soient générés en parallèles est une très bonne idée. On peut alors sortir le format que l'on souhaite. Il n'y a pas d'obligation de licence.\newline
\end{itemize}

Il faut à présent se pencher sur l'ergonomie du document HTML généré.
La page de garde offre un visuel assez agréable. Elle permet dès le départ de choisir au moyen d'onglets entre les pages de documentation technique, ou les pages de vulgarisation. Au niveau des pages de vulgarisation, leur aspect est très correct. Grâce aux balises, le rédacteur peut réaliser une très jolie documentation.

\begin{center}
\begin{figure}[h!]
 \includegraphics[scale=1]{Images/Doxygen-screen-main.png}
 \caption{Page principale de Doxygen}
 \label{doxygen-screen-main}
\end{figure}
\end{center}


Ensuite, Il faut se pencher sur l'aspect de la documentation technique. Pour y accéder, il suffit de cliquer sur l'onglet \textit{Files}. On peut alors choisir les fichiers à regarder. Seuls sont présents ceux où une documentation est définie. Nous y trouvons donc des informations non indiquées par le rédacteur, tel que la liste des fonctions. Si une description existe pour une fonction, alors un lien est disponible afin de s'y rendre directement.
De plus, si un élément documenté est mentionné, au travers d'un type retourné, par exemple, alors le nom est aussi un lien hypertexte permettant de rejoindre la documentation correspondante.

\paragraph{}Il existe aussi l'onglet \textit{Files members} compris dans l'onglet \textit{Files} permettant de retrouver chaque élément invisible du point de vue des fichiers. 

\begin{center}
\begin{figure}[h!]
 \includegraphics[scale=0.5]{Images/Doxygen-screen-all.png}
 \caption{Liste des éléments sous Doxygen}
 \label{Doxygen-screen-all}
\end{figure}
\end{center}


On pourrait critiquer le fait que tous ces onglets dépliés les uns sous les autres occupent de l'espace, mais dans l'ensemble, cette application est très solide. On peut dire que l'on a fait le tour de Doxygen.

\subsubsection{Javadoc}


Nous allons à présent étudier Javadoc, un logiciel permettant de générer de la documentation exclusivement pour le langage Java. Cet outil est fourni avec le JDK\footnote{Java Development Kit}. Ainsi, l'outil de documentation accompagne toujours le langage, du moins la plupart du temps. Ce logiciel en est déjà à la verion 5.0 et est développé par Sun.

\paragraph{}Il est inutile de recommencer à décrire l'ensemble des balises car ce sont sensiblement les mêmes que celles de Doxygen. La principale différence est que le nom des balises commence par le caractère \textit{arobase}, et non \textit{antislash}. La réelle différence se fait déjà sentir dans quelques balises exclusives à Javadoc. Ce générateur étant spécifique à un unique langage, il a été développé en fonction. Par exemple, on peut trouver la balise \textit{@throws} qui permet de décrire une exception.

\paragraph{}A présent, il faut se focaliser sur l'aspect graphique des pages HTML générées. Quand on ouvre le fichier \textit{index.html}, on se retrouve face à des éléments déconcertants. En effet, l'aspect manque d'esthétique. Les pages sont assez tristes et n'apparaissent pas très modernes.

\begin{center}
\begin{figure}[h!]
 \includegraphics[scale=0.35]{Images/Javadoc-screen.png}
 \caption{Page d'index générée par Javadoc}
 \label{Javadoc-screen}
\end{figure}
\end{center}

\paragraph{}Bien que l'aspect paraisse rustique, il faut se pencher sur les possibilités offertes. Tout d'abord, il existe un système visant à personaliser légèrement sa façon de naviguer. En effet, la \textit{frame} sur le côté gauche peut être redimensionnée. De plus, il y a même un bouton servant à la faire disparaître. Le fait de pouvoir disposer constamment de la liste des objets peut réellement aider à naviguer.

\paragraph{}Ensuite, on remarque que les différentes sections sont continuellement disponibles : Package, Tree, Index, Deprecated, About. De cette façon, l'utilisateur peut rejoindre quand il le veut la rubrique de son choix. Il est dommage que ces liens soient affichés sur toutes les pages. Cependant, pour limiter le nombre de cliques, cette solution fut probablement la meilleure.

Un autre bon outil que l'on retrouve dans Javadoc est la proximité avec Eclipse. En effet, une commande est directement mise à disposition dans Eclipse afin de générer la documentation. Bien que cela ne concerne pas directement la navigation dans la documentation, ni la définition des balises, cette intéraction mérite d'être soulignée.

\paragraph{}Nous avons donc remarqué toute une série de bons concepts dans ces deux générateurs de documentation.


\paragraph{} Quelques documentations en lignes ont servi d'inspiration afin réaliser un outil intéractif.
Pour cela, il semblait approprié d'analyser la documentation du framework Flex et du langage Actionscript, apportant ainsi une double utilité. Il était à la fois intéressant d'observer une documentation structurée efficacement,  et aussi d'en apprendre plus sur le framework Flex.

\newpage
\subsection{Analyse des besoins}

Afin de réaliser un éditeur de documentation acceptable, il a fallu réfléchir aux besoins auxquel ce logiciel devait répondre. Ces dernier ont beaucoup évolué au cour du projet. Avant d'aborder le codage, des bases solides avaient été établies et l'aspect général de Jam était déjà assez précis. Néanmoins, tout au long du développement, certaines idées émergent, et d'autres se révèlent finalement inutiles une fois qu'on les a appliquées réellement. Il faut donc préciser que durant toute la phase de développement, beaucoup de modifications ont été apportées dans les besoins que devaient remplir le logiciel. Certaines idées ont été écartées pour des raisons de faisabilité. Nous allons donc exposer une version finale des besoins, sans présenter toutefois l'intégralité des évolutions subies.\\

\begin{itemize}
 \item Un système de vue : Il s'est révélé qu'afin d'avoir un outil à la fois ludique et pertinent, il fallait que certaines éléments soient visibles de manières différentes. Une classe, par exemple, fournit certaines informations intéressantes, comme son arborescence. Mais elle en fournit aussi encore d'autres tout aussi pertinentes, comme ses fonctions, la documentation associée. Au lieu d'avoir toutes ces informations réunies en une seule page, comme dans la plupart des documentations générées, il a été décidé d'opter pour un système de vue. Ainsi, un élément peut être vu de plusieurs façons suivant l'envie de l'utilisateur. Cela permet d'éviter d'avoir à l'écran des informations susceptibles de ne pas intéresser le lecteur.\\

 \item Un système de \textit{split} façon Blender : C'est un des besoins imposé par Atonce dès le début de la définition des besoins. La direction d'Atonce aimait beaucoup le système de Blender qui consiste à subdiviser à loisir l'application. Certaines vues n'étant pas tout le temps pertinentes, il était dommage qu'elles soient constemment visibles. Ainsi, grace à ce système de \textit{split}, l'utilisateur peut choisir à loisir de rajouter ou d'enlever des vues. Il décide quelle place prendra chaque vue et où elle sera disposée.\\

 \item Une vue navigateur : C'était en quelque sorte l'élément innovant de cet éditeur de documentation. Il fallait pouvoir naviguer entre les informations de façon ludique avec des effets graphiques originaux. Le but était donc de disposer d'une vue qui permette uniquement d'observer les éléments les uns par rapport aux autres. SIDL permettant de décrire des éléments de façon originale pour du C++, il fallait disposer d'une vue qui mette l'accent sur cette représentation. La seule prérogative était de disposer d'éléments plutôt en forme de cercle, avec autour les éléments en rapport avec l'élément central.\\

 \item Une vue page : Cette vue a été imaginée car il fallait pouvoir observer la documentation écrite associée à un élément. C'est un aspect assez traditionnel de la documentation de projet : une classe, dispose de tout un tas d'informations décrivant son fonctionnement, de quelques exemples de code pour mieux l'illustrer. Il fallait pouvoir accéder à toutes ces données. Afin d'optimiser l'ergonomie, il est apparu que de disposer d'une série de liens vers certains autres éléments en rapport serait assez pertinant. Ainsi, pour une classe par exemple, ce serait la liste des fonctions la composant.\\

 \item Un système de recherche : Cette application n'étant pas un simple ensemble de pages HTML comme pour la plupart des documentations, il fallait disposer aussi d'un système efficace permettant de trouver l'information. Sur beaucoup de documentations en ligne, celle d'Actionscript ou de Java par exemple, l'utilisateur dispose d'un petit moteur de recherche permettant un usage rapide. Ce système de documentation se devait d'en posséder un lui aussi. C'est donc pour cela qu'il fut imaginé.\\

 \item Un système de filtres : Cette idée pouvait être couplée à l'idée de recherche. Comme souvent, lorsque l'on effectue une recherche dans n'importe quel domaine, on se retrouve confronté au problème de la masse des informations inutiles données en résultat. On s'est rapidement rendu compte que l'utilisateur pourrait être confronté à des projets se composant de plusieurs milliers de classes. Pour rechercher un objet en particulier, cela devient très problématique. L'application étant très visuelle, disposer de plusieurs centaines d'objets à l'écran s'avère destabilisant pour un utilisateur lambda. Il fut donc décidé d'implémenter un système de filtre afin de trier les informations sélectionnées. Ainsi, lorsque l'on lancerait une recherche, on choisirait de ne montrer que les classes, ou que les interfaces. De cette façon l'utilisateur ne choisirait de voir que ce qui l'intéresse.\\

 \item Un système de sauvegarde de la configuration : Le principe de découper l'application afin d'obtenir une meilleure personnalisation de l'IHM apparait intéressante, mais il faut aussi disposer d'outils adaptés à une telle interface. Un utilisateur finira par adopter une configuration qu'il jugera efficace, pratique, ou tout simplement jolie. L'inconvénient est qu'il devra constemment la recréer lors de chaque utilisation. Il semble donc extrêmement utile de pouvoir disposer d'une sauvegarde de la configuration. Ainsi, l'utilisateur n'a plus qu'à recharger sa configuration favorite afin de lui faire gagner un temps précieux. Cette idée apporte en plus l'avantage de disposer d'un certain nombre de configurations par défaut. De cette façon, un utilisateur qui n'aurait pas envie de perdre son temps à configurer l'application pourrait partir directement d'une configuration correspondant à ses besoins.\\

 \item Un système de marque-page : Lorsque l'on parcourt les documentations en ligne, on se rend compte que certaines pages web sont plus utiles que d'autres. En effet, on revient constemment sur les mêmes pages de documentations. Par exemple, lorsqu'un programmeur parcourt la documentation du langage Java, il reviendra souvent sur la documentation de la même classe. Pour y revenir plus aisément, il se servira d'une fonctionnalité intéressante de son navigateur qui est le marque-page. Jam se devait de disposer de cet outil afin de faciliter la vie des utilisateurs habitués à l'exploration par navigateur web dans les documentations. Ainsi, il a été décidé que ce système de marque page s'apparenterait à une vue. De cette façon, l'utilisateur pourrait choisir de ne pas les voir pour ne pas perdre de place en cas de non utilité.\\

 \item Un mécanisme universel de \textit{drag and drop} : Il a été décidé que tout élément référencé par un autre élément pourrait être \textit{dragué} vers une autre vue afin d'en savoir plus. Par exemple, si la page de documentation d'une classe contient des liens vers d'autres éléments, vers les fonctions qu'elle contient par exemple, alors ces liens seront \textit{draggables} et \textit{déposables} vers d'autres vues, comme le marque-page par exemple. Ainsi, c'est peut être l'objectif le plus délicat à réaliser car il faut bien voir que c'est au niveau de l'architecture que tout se joue. Chaque élément affichable doit être en quelque sorte universel et donc doit pouvoir communiquer avec le reste de l'application. C'est très certainement cet objectif qui a demandé le plus d'effort.\newline

 \item Réalisation d'une version imprimable de la documentation : Disposer d'un logiciel permettant de naviguer dans la documentation de façon ludique est, certes , un atout de poid, mais il peut en dérouter plus d'un. De plus, il est alors assez difficile de faire transiter la documentation d'une personne à une autre. En outre, lire d'innombrables pages de documentation n'est pas très agréable derrière un écran. Il s'avere donc indispensable de disposer d'un document imprimable. Ainsi, si les rédacteurs ont créé une oeuvre de plusieurs centaines de pages, ils peuvent la lire directement sur papier. Pour réaliser cet objectif, il fallait cerner de façon pertinente comment les rédacteurs pourraient personnaliser cette oeuvre imprimable, penser à des moyens qui leur permettraient de rajouter des pages entre les documentations d'élémens, mais aussi organiser le tout en différentes parties et sous parties.
\end{itemize}


\subsection{Définition des normes}


Au début du projet, il fallait avant tout définir un certain nombre de formats. En effet, il avait été décidé assez tôt que sugar générerait un fichier XML qui servirait à porter l'information de la documentation pour Jam. Evidemment, la réalisation du code permettant de générer le fichier XML était censée se dérouler en même temps que la réalisation de Jam. Il fallait donc que toute la spécification du format XML et des commandes SIDL servant pour la documentation soient définies avant.

\subsubsection{Liste des commandes de documentation SIDL}

Il faut tout d'abord définir la liste des commandes possibles à mettre dans le fichier SIDL avant d'étudier leur représentation en XML. SIDL dispose d'une balise servant à définir la documentation : @doc. Toutes les balises doivent donc être insérée dedans.
Voici donc une liste non exhaustive des commandes qui furent implémentées ou au moins, imaginées :\newline
\begin{itemize}

 \item Les balises $\backslash$implementation, $\backslash$function, $\backslash$interface : Sugar ne disposant à ce jour que des éléments implementation, interface, ou function, ces balises permettent de documenter uniquement les éléments de ce type. Pour s'en servir, il suffit de mettre, dans les limites des balises \textit{@doc}, la balise correspondant au type que l'on souhaite documenter. Ensuite, il faut mettre le nom de l'élément à documenté et toutes les balises de documentation qui suivront concerneront alors l'élément défini. Par exemple, si l'on veut documenter l'interface IMatrix, alors il suffit d'appeler la commande \textit{$\backslash$interface IMatrix} et toute les commandes de documentation qui suivront concerneront l'interface IMatrix. Si ensuite il est nécessaire de documenter l'élément MMatrix2D, alors il faut appeler la commande \textit{$\backslash$implementation MMatrix2D} et les commandes suivantes ne concerneront plus IMatrix, mais MMatrix2D.\\

 \item Les balises $\backslash$\$+, $\backslash$\$-, et $\backslash$\$\$ : Ces balises permettent quant à elles de définir les éléments à documenter de façon relative. Tout simplement, si l'on veut documenter l'élément suivant dans le fichier SIDL par rapport à la position de la balise @doc, il suffit alors d'utiliser la commande $\backslash$\$- car c'est l'élément qui se situe un cran plus bas dans le fichier. De même, $\backslash$\$+ permet de documenter ceux qui sont un cran plus haut. La balise $\backslash$\$\$ quant à elle, permet de définir l'élement courant. Par exemple, si l'on est dans la définition d'une interface et que l'on place une balise \textit{@doc}, alors la balise $\backslash$\$\$ permettra de la définir.\\

 \item La balise $\backslash$brief : Comme on peut le remarquer dans un certain nombre de documentations, il y a toujours une petite partie qui sert de résumé pour comprendre l'élément documenté. Ici, les détails ne sont pas réellements fournis, mais cela permet de se faire une idée rapide de l'utilité de l'élément observé.\\

 \item La balise $\backslash$long : Cette balise permet de désigner une partie explicative bien plus longue. Si le rédacteur désire approfondir son sujet, il donnera alors beaucoup plus de détails. Cette partie est censée venir après la partie brief.\\

 \item La balise $\backslash$author : Sans surprise, cette balise permet de préciser le nom de l'auteur qui a créé l'élément documenté.\\

 \item La balise $\backslash$version : De la même façon que la balise $\backslash$author, cette balise permet de définir la version de l'élément documenté.\\

 \item La balise $\backslash$date : Ici, cette balise permet de définir la date de création de l'élément documenté.\\

 
\end{itemize}

C'est donc la liste des principales balises qui furent créées afin de définir la documentation dans le code source SIDL. Cette structure, bien que relativement classique semblait assez fiable. En l'utilisant, il apparait que les rédacteurs devant rédiger les futurs documentations ne seront pas trop désorientés et pourront ainsi s'abstraire de la représentation originale de l'outils Jam.

\paragraph{}Il a fallu ensuite définir comment formaliser toutes ces informations afin de communiquer efficacement avec Jam. Si le format XML fut très rapidement choisi, c'était bien entendu afin de bien séparer l'outil Sugar de l'outil Jam. Donc même un autre outil pourrait lire le fichier et interpréter différemment les informations qu'il contient. De plus, un autre réel avantage pour l'utilisateur, il n'est pas obligé de disposer du code source documenté. Il lui suffit de disposer du fichier XML généré pour en avoir la documentation. De cette façon, cette représentation offre une certaine liberté.

\paragraph{}Pour bien comprendre le XML qui fut créé, il faut avant tout comprendre le type de fichiers XML générés par gccxml. Il est indéniable que ce format fut une réelle inspiration afin de créer le format XML pour Jam.
Bien qu'il ait été évoqué brièvement, examinons en détail le fichier XML généré par gccxml.

\subsubsection{Fichiers XML générés par gccxml :} Ces fichiers sont générés à partir d'un code source C ou C++. Ils permettent de retrouver toutes les relations entre les éléments que l'on retrouve dans le code. Naturellement, le fichier XML généré ne donne aucune information sur les algorithmes présents dans les fonctions. On n'y retrouve que les fonctions, les classes dans lesquelles elles sont définies, les types de leurs arguments, leurs noms, ainsi de suite. Comme nous l'avions déja étudié dans la partie sur les outils utilisés, rappelons que chaque objet est défini par une balise. Par exemple, prenons une classe contenant deux fonctions, chacune prenant deux arguments de type entiers, alors nous aurons quatre noeuds frères dans l'arbre XML. Un noeud définira la classe, deux noeuds définiront les fonctions, et un dernier noeud définira le type entier. Chaque noeud dispose d'un identifiant unique, qui en plus correspond à son numéro par rapport à leur père.
Ensuite, nous trouvons des références reliant ces noeuds entre eux. Par exemple, la balise définissant la classe possède deux noeuds XML fils qui représentent les fonctions définies dans cette classe. Ces balises contiennent un attribut \textit{ref} qui indique l'identifiant des noeuds représentant les fonctions. Ainsi, il est facile de retrouver ces fonctions. 

\paragraph{}De la même façon, les balises représentant les fonctions contiennent des noeuds XML fils représentant les arguments. Ces noeuds XML disposent eux aussi de l'attribut \textit{ref} désignant l'identifiant des types de ces arguments.
De surcroit, les informations propres à chaque élément, comme le nom par exemple, sont définies par des attributs dans les balises correspondantes. Par exemple, si le nom d'une fonction est \textit{f2}, alors le noeud XML la représentant contiendra un attribut \textit{name} qui aura pour valeur \textit{f2}.

Le plus simple pour bien comprendre est de se servir soi-même de gccxml.

Les éléments sont, bien que définis au même niveau, hiérarchisés. Une classe contient des fonctions, les fonctions contiennent des arguments qui référencent des types.
Voyons comment ce modèle fut adapté pour la représentation de la documentation.

\subsubsection{Représentation de la documentation en XML}

Pour représenter la documentation en XML, l'inspiration est donc venu de la représentation de gccxml. Nénamoins, il fallait avant tout définir une certaine hiérarchie. En effet, bien que chaque élément soit défini au même niveau, ils peuvent se référencer les uns les autres au moyen de balises spécifiques.
La hiérarchie qui fut choisie est la suivante : Les implémentations contiennent les interfaces qui contiennent les fonctions. 
Ainsi, il a été défini toute une collection de balises permettant de représenter chaque objet :\newline
\begin{itemize}
 \item Les implémentations : Pour les implémentations, il semblait assez pertinent d'utiliser une balise nommée tout simplement IMP. Evidemment, elle contient tout un nombre d'attributs donnant de plus amples informations. Notamment :
 \begin{itemize}
  \item Un attribut \textit{id}, pour donner l'identifiant unique de cette implémentation,
  \item Un attribut \textit{name}, pour connaitre son nom,
  \item L'attribut file, qui définit le chemin complet où cette implémentation est définie.
  \item L'attribut line, indique à quelle ligne commence la définition de cette implémentation. 
 \end{itemize}

Il faut savoir que ce noeud XML ne peut avoir qu'un type de noeud fils : le noeud \textit{concerns} qui permet de définir les identifiants des interfaces dont hérite cette implémentation. La balise \textit{concerns} dispose donc de l'attribut type qui indique cet identifiant.\newline
% insérer un screenshot d'une balise IMP

 \item Les interfaces : Le cas des interfaces se présente de manière similaire à celui des implémentations. L'attribut id donne l'identifiant, \textit{name} défini le nom, \textit{file} le chemin du fichier où est situé cette interface, et \textit{line} indique la ligne. La seule différence avec IMP est dans les balises qu'elle peut avoir pour fille. En effet, elle dispose des balises \textit{function} qui donnent l'identifiant des fonctions données par l'interface au moyen de l'attribut \textit{type}. Il est évident que la balise \textit{function} est très proche de la balise \textit{concerns}.\\
% insérer un screenshot d'une balise ITF

 \item Les fonctions : Les balises définissant les fonctions sont bien entendu extrêmement proches de la représentation de gccxml. En effet, c'est à peu près le même élément, puisque ce ne sont que de simples fonctions C++. Elles sont donc représentées par la balise FUN qui contient les attributs habituels, tel que \textit{name} pour le nom, \textit{id} pour l'indentifiant, \textit{file} pour le fichier, et \textit{line} pour la ligne. Ensuite, deux attributs spécifiques très utiles ont été rajouté pour les fonctions. L'un de ces deux attributs est \textit{return}. Il permet de donner la chaine de caractère du type de retour. Ensuite, l'attribut \textit{context} permet de retrouver l'identifiant de l'interface où est définie cette fonction. De la même manière que pour les autres éléments, la balise FUN peut avoir des balises filles donnant les arguments de la fonction. Ce sont les balises \textit{argument}, qui contiennent deux attributs : \textit{name}, qui défini le nom de l'argument, et \textit{type}, qui indique le nom du type de l'argument.\\
% insérer un screenshot d'une balise FUN
\end{itemize}

En observant cette liste de balises, il semble frappant que, contrairement à gccxml, les types ne disposent pas de balises spécifiques. En réalité, ils ne sont même pas représentés autrement que par des chaines de caractères. La raison étant que, pour les pointeurs, cela donnait des références multiples qui au final débouchaient sur des objets peu importants pour la documentation, comme les \textit{int} par exemple. De plus, il devenait assez difficile de retrouver un type de variable caché par une multitude de pointeurs successifs.
Le plus explicite s'est donc avéré de passer par des chaînes de caractères.

Pour explicité ce format, voici un exemple désignant un code simple :

\begin{center}
\begin{figure}[h!]
 \includegraphics[scale=0.5]{Images/Exemple-XML.png}
 \caption{Exemple de fichier XML}
 \label{exemple-xml}
\end{figure}
\end{center}

Ensuite, il faut voir que la représentation du XML n'est pas encore complétement terminée. En effet, il y a une partie de ce standard qui ne concerne plus le langage SIDL, mais directement le C++. Comme nous l'avons déja abordé, SIDL permet d'importer directement des fichiers C++ ou des morceaux de code. Tout ce code n'est pas analysé par SIDL et doit donc l'être par gccxml. cela donne donc de nouvelles balises, spécifique au code C++.\newline

\begin{itemize}
 \item Les balises NAMESPACE : le concepte de \textit{namespace} n'existe pas réellement dans le langage SIDL. Néanmoins, il peut s'avérer intéressant de le prendre en compte. Il ne contient que les attributs \textit{name} pour le nom et \textit{id} pour l'identifiant. N'étant pas un objet SIDL, les autres attributs n'avaient pas de sens. Il contient les balises CLASS qui référencent les interfaces ou les implémentations qui sont contenues dans le namespace. De plus il contient les balises \textit{namespace} qui définissent les \textit{namespaces} contenus dans ce dernier.\newline
% insérer un screenshot d'une balise NAMESPACE

 \item Les balises CLASS : Elles permettent de définir les classes exclusives qui ont été trouvées dans les fichiers C++. Elles s'apparentent aux balises ITF car elles ont une structure assez proche. On y retrouve donc les attributs \textit{name} pour le nom, \textit{id} pour l'identifiant, mais aussi \textit{file} pour le fichier et \textit{line} pour la ligne. Pour l'attribut \textit{context}, on indique ainsi à quel \textit{namespace} appartient cette classe. Ensuite la classe ne peut contenir que des fonctions qui sont référencées au moyen de la balise function. Cela s'apparente donc bien à la représentation des interfaces.\newline
%insérer un screenshot d'une balise CLASS

 \item Les balises METHOD : Ces balises permettent de représenter les fonctions qui sont spécifiques aux fichiers C++. Elle se présentent de la même façon que les balises FUN. Elles disposent des attributs \textit{id}, \textit{name}, \textit{file}, \textit{line} et enfin de \textit{return} pour indiquer le type de retour. Elles peuvent avoir comme balise filles les balises \textit{argument}, qui sont les mêmes que pour les autres fonctions. Elles disposent donc des attributs \textit{name} pour le nom et \textit{type} pour le type.\newline
%insérer un screenshot d'une balise METHOD

\end{itemize}

Toutes ces balises permettent donc de hiérarchiser les objets entre eux. A partir de ce fichier XML, on pourrait d'ailleurs reproduire l'ossature de tout le projet défini au moyen de SIDL. Il faut constater qu'il y a encore un manque important au standard XML qui vient d'être défini. Il manque en effet toutes les balises permettant de définir la documentation rédigée par le rédacteur.
Ces balises se présentent simplement car elles sont toutes contenues dans la déclaration de l'élément qu'elles documentent. Par exemple, les balises de documentation d'une fonction, seront filles de la balise FUN définissant la fonction.
Voici la liste des balises donnant la documentation :\newline

\begin{itemize}
 \item La balise brief : Contient la chaine du \textit{brief}. Ne dispose pas d'attributs.\newline
 \item La balise title : Définit le titre de cette page de documentation. Ne dispose pas d'attributs.\newline
 \item La balise date : Définit la date de création de l'élément. Ne dispose pas d'attributs.\newline
 \item La balise version : Définit la version de l'élément. Ne dispose pas d'attributs.\newline
 \item La balise long : Définit le corps de la documentation de l'élément. Ne dispose pas d'attributs.\newline
 \item La balise ref : Obligatoirement fille d'une balise de documentation, elle spécifie un lien. Elle dispose de l'attribut \textit{ref} qui donne l'\textit{id} de l'élément vers lequel le lien pointe.\newline
%screenshot d'un exemple complet.
\end{itemize}

De cette façon, à partir du fichier XML il est possible de retrouver tous les objets SIDL et toute la documentation correcpondante. Il faut voir que la documentation spécifique au PDF généré ne se retrouve pas ici car il n'y a aucune raison de l'afficher dans Jam. On peut dire que les éléments spécifiques au C++ ne sont pas documentables, bien qu'ils soient atteignables et référençables. Les seules informations que donnent Jam sont les relations qu'ils ont.


Nous allons aborder dans cette partie notre projet réalisé dans la société Atonce technologies.

